What is next.config.js and what can you configure in it?

next.config.js is the main configuration file for Next.js that allows you to customize build settings, enable features, and configure various aspects of your application's behavior

The next.config.js file (or next.config.ts for TypeScript) is a Node.js module that sits at the root of your Next.js project and controls how the framework builds and runs your application. This file exports a configuration object that Next.js reads during build time and runtime, enabling you to customize everything from image optimization to build output directories, environment variables, and experimental features. Starting with Next.js 15, you can write this configuration file in either JavaScript or TypeScript for better type safety .

Basic next.config.js Structure

Core Configuration Categories

Build and Compilation: Configure how Next.js builds your application. Options include swcMinify (use Rust-based SWC minifier), compiler (customize SWC transforms), and webpack (customize webpack configuration). The default compiler is SWC, which is significantly faster than Babel .
Images and Assets: The images configuration allows you to define image optimization behavior, including remote patterns (allowed image domains), image sizes for responsive images, and formats like WebP and AVIF. You can also disable image optimization if needed .
Redirects and Rewrites: Configure server-side redirects, rewrites, and headers through functions like redirects(), rewrites(), and headers(). These run before the response is sent and can be used for SEO, A/B testing, or proxy patterns .
Environment Variables: Control environment variable exposure with env (build-time env vars) and publicRuntimeConfig (client-side available variables). You can also use .env files which are automatically loaded .
Internationalization: Configure i18n routing with i18n object, specifying locales, default locale, and domain-based locale detection. This enables automatic language detection and prefixed routes .

Common Configuration Examples

Advanced Configuration Options

Experimental Features: Next.js provides a experimental object to enable cutting-edge features like instrumentationHook (for monitoring), typedRoutes (experimental type-safe routes), or serverActions (enabled by default in Next.js 15). These features are subject to change .
Custom Webpack: For advanced use cases, you can extend Next.js's internal webpack configuration using the webpack function. This allows adding custom loaders, plugins, or modifying the build pipeline, but should be used with caution .
Middleware Configuration: Configure middleware behavior with matcher options to specify which paths should run middleware. This is typically done in the middleware.ts file itself, but related config can be placed here .
Output Configuration: Control the build output format with output: 'standalone' for self-hosted deployments (creates a minimal standalone folder), or output: 'export' for static HTML exports .
Server Component Configuration: Configure server component behavior, including the external packages list that should be bundled and runtime options .

If you're using TypeScript, you can use next.config.ts instead of .js for better type checking and autocompletion. Next.js automatically detects this file and applies TypeScript validation. The configuration object is typed with import('next').NextConfig, providing IntelliSense for all available options. This is particularly helpful when working with complex configurations or team projects .

TypeScript Configuration Example

Environment-Specific Configurations

Development vs Production: You can use process.env.NODE_ENV in your config file to apply different settings for development, production, or test environments .
Phase-based Configuration: Next.js provides phases like PHASE_DEVELOPMENT_SERVER and PHASE_PRODUCTION_BUILD that you can import from 'next/constants' to conditionally apply configuration .
Runtime Configuration: For values that need to be available at runtime (not build time), use publicRuntimeConfig and serverRuntimeConfig for client-side and server-side values respectively .
Dynamic Configuration: The config file can export an async function that receives phase and defaultConfig parameters, allowing for programmatic configuration generation .

Question Loading...